Atlassian Integration Guide : Dragons Stage 4 - Install Confluence
This page last changed on Apr 13, 2011 by smaddox.


There will be much flapping of wings and breathing of fire. You are embarking on stage 4 of the Atlassian Dragon Quest.

In this stage, you will install Atlassian Confluence, the enterprise wiki. You will hook Confluence up to Crowd for SSO and centralised user management, and get your JIRA and Confluence sites talking to each other. Then you will create a wiki space, add a dynamic display of JIRA issues to a wiki page, and add a Confluence activity stream to your JIRA dashboard.

Time estimate: This stage will take approximately 60 minutes.

On this page:

Step 1. Create your Confluence Database in PostgreSQL

Now you will create a database where the Atlassian Confluence application will store its data, and the user that Confluence will use to connect to the database. We are assuming that you have already created your PostgreSQL database server in Dragons Stage 1.

We are using pgAdmin III, the administration user interface supplied with PostgreSQL. If you used the one-click installer in Dragons Stage 1, pgAdmin III will be already installed on your computer.

  1. Start pgAdmin III.
  2. Add a new login role called 'confuser':
    • Right-click 'Login Roles' and select 'New Login Role'.
    • Enter the 'Role name': confuser.
    • Enter a 'Password' and enter it again to confirm it.
    • Click the 'Role privileges' tab.
    • Select 'Can create database objects'.
    • Select 'Can create roles'.
    • Click 'OK' to create the user.
  3. Add a new database called 'confluence':
    • Right-click 'Databases' and select 'New Database'.
    • Enter the database 'Name': confluence.
    • Select the 'Owner': confuser.
    • Click 'OK' to create the database.

Alternatively, If you are on UNIX and do not have pgAdmin III, you can use the command line interface instead. Assuming that you are using the default installation directory of /opt/PostgreSQL/8.3/bin/, enter the following commands:

sudo -s -H -u postgres
# Create the Confluence user:
/opt/PostgreSQL/8.4/bin/createuser -S -d -r -P -E confuser
# Create the Confluence database:
/opt/PostgreSQL/8.4/bin/createdb -O confuser confluence
exit

Screenshot 1 (click to enlarge): Confluence database and user in PostgreSQL

Step 2. Install Confluence

Requirements: Confluence 3.5.

For Windows: (click to expand)
  1. Go to the Atlassian download centre.
  2. Download the 'Standalone (ZIP Archive)' file for 3.5.
    Do not use the 'Windows Installer' for this integration exercise, because the workflow for configuring an external database is simpler when installing from the zip archive. If you cannot see the 'Zip Archive', click the 'Show all' link above the download buttons to see all the download file types.
  3. Unpack the zip archive into a directory of your choice, avoiding spaces in the directory name.
  4. Tell Confluence where to put its Confluence Home directory:
    • Edit the properties file at {CONFLUENCE_INSTALL}\confluence\WEB-INF\classes\confluence-init.properties.
    • Remove the hash sign (#) in front of the following line, and enter the directory name:
      # confluence.home=c:/confluence/data
      For example:
      confluence.home=c:/data/confluence-home
      (Note the forward slashes.)
    • Save the file.
  5. Because Confluence will be running on the same machine as JIRA (already installed), you need to ensure that the application server ports for Confluence and JIRA are different. By default, both applications use port 8080. Change the default Confluence port as follows:
    • Edit the configuration file at {CONFLUENCE_INSTALL}\conf\server.xml.
    • Change the value of the port attribute in the Connector element to 8090.
  6. Start your Confluence server by running {CONFLUENCE_INSTALL}\bin\startup.bat.
For UNIX or Linux: (click to expand)
  1. Go to the Atlassian download centre.
  2. Click the 'Linux' tab and download the 'Standalone (TAR.GZ Archive)' file for Confluence 3.5.
  3. Unpack the tar.gz archive into a directory of your choice, avoiding spaces in the directory name.
  4. Tell Confluence where to put its Confluence Home directory:
    • Edit the properties file at {CONFLUENCE_INSTALL}/confluence/WEB-INF/classes/confluence-init.properties.
    • Remove the hash sign (#) in front of the following line, and enter the directory name:
      # confluence.home=c:/confluence/data
      For example:
      confluence.home=/var/confluence-home
    • Save the file.
  5. Because Confluence will be running on the same machine as JIRA (already installed), you need to ensure that the application server ports for Confluence and JIRA are different. By default, both applications use port 8080. Change the default Confluence port as follows:
    • Edit the configuration file at {CONFLUENCE_INSTALL}/conf/server.xml.
    • Change the value of the port attribute in the Connector element to 8090.
  6. Start your Confluence server by running {CONFLUENCE_INSTALL}/bin/startup.sh.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 3. Set Up Confluence

Now you can run Confluence's Setup Wizard and change some configuration settings.

  1. To access Confluence, go to your web browser and type this address: http://localhost:8090.
  2. The Confluence Setup Wizard will start up, to guide you through the process of setting up your Confluence server and creating an administration user. Detailed instructions are in the Confluence documentation.
  3. Enter your Confluence license into the 'License Key' field. If you do not already have a Confluence license, follow the prompts on the Setup Wizard screen to generate an evaluation license online.
  4. Click 'Production Installation' under 'Choose Installation Type'.
  5. The 'Choose a Database Configuration' screen will appear. Connect Confluence to your PostgreSQL database:
    • In the 'External Database' section, ensure that 'PostgreSQL' is selected and click the 'External Database' button.
    • The 'Configure Database' screen will appear. Click the 'Direct JDBC' button in the 'Direct JDBC Connection' section.
    • Enter the following information:
      • Driver Class Name: org.postgresql.Driver – This is the default value.
      • Database URL: jdbc:postgresql://localhost:5432/confluence – This is the default value.
      • Username: confuser – This is the user you created in step 1 (above).
      • Password – Enter the password that you chose in step 1 (above).
    • Click the 'Next' button. You might need to wait a few minutes while Confluence sets up its database.
  6. On the 'Load Content' screen, click the 'Example Site' button to include the demonstration space content into your Confluence installation:.
  7. The 'Setup System Administrator' screen will appear. Enter the following information:
    • Username: charlie
    • Password – Enter a password for the administrator account and enter it again in the 'Confirm' field to confirm it.
    • Name: Charlie of Atlassian
    • Email – We recommend that you give your own email address here.
  8. Click the 'Next' button.
  9. The 'Confluence Setup Successful' screen will appear. Click 'Start using Confluence now'.
  10. The home page of the Confluence 'Demonstration Space' will appear.
  11. Finally, you need to change your Confluence Server Base URL to the full (website) address at which Confluence is running, not just 'localhost':
    • Open the 'Browse' menu at the top of the screen and select 'Confluence Admin'. Confirm your password when prompted.
    • The 'Administration Console' screen will appear. Click 'General Configuration' under 'Configuration' in the left-hand panel.
    • The 'General Configuration' screen will appear. Click any of the 'Edit' links.
    • In the 'Server Base Url' field of the 'Site Configuration' section, enter the full website address at which Confluence is running. This address should not be 'localhost'. For example, if your computer name is 'coopers' then the server base URL should be: http://coopers:8090. Alternatively, specify a website address such as http://www.foobar.com:8090.
    • Scroll down to the end of the page and click the 'Save' button.

Screenshot 2 (click to enlarge): Home page of the Confluence demo space

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 4. Hook Confluence up to Crowd

In this step you will configure Confluence to use Crowd for SSO and centralised user management. To do that, you will define the Confluence application in Crowd, define the Crowd user directory in Confluence , and configure the SSO property files.

  1. If Crowd is not already running, start it up by running {CROWD_INSTALL}/start_crowd.bat and go to your Crowd URL in your browser, e.g. http://www.foobar.com:8095/crowd.
  2. Log in to Crowd with username charlie.
  3. Click 'Applications' in the top navigation bar.
  4. The 'Application Browser' will appear. Click 'Add Application' in the left-hand menu.
  5. This will display the first screen for the 'Add Application' wizard for Crowd. Enter the following information:
    • Application Type: Confluence
    • Name: confluence
    • Description: Atlassian Confluence
    • Password – Enter a password that Confluence will use to access Crowd and enter it again to confirm it.
    • URL – Enter the base URL of your Confluence site, as configured in step 3 above, e.g. http://www.foobar.com:8090.
    • Click 'Resolve IP Address' to ask Crowd to find the 'Remote IP Address' for you. The value will be something like this: 127.0.0.1.
    • Select the 'Crowd' directory that you created in Dragons Stage 1.
    • Select 'Allow all users to authenticate'.
    • Click 'Add Application'.
  6. Check the IP addresses for your Confluence application:
    • Click the 'Remote Addresses' tab.
    • Add your Confluence host name, excluding the "http://www." prefix and the ":8090" port number. e.g. foobar.com.
    • If this address is not already present, add it: 127.0.0.1.
  7. Connect Confluence to the Crowd user directory:
    • Go to your Confluence URL in your browser, e.g. http://www.foobar.com:8090.
    • Select 'User Directories' from the 'Security' section of the Confluence Administration Console.
    • Click 'Add Directory', select type 'Atlassian Crowd' and click 'Next'.
    • The Crowd server configuration screen will appear. Enter the following information:
      • Name – Accept the default value, Crowd Server.
      • Server URL – Enter the web address of your Crowd server, e.g. http://www.foobar.com:8095/crowd
      • Application Name: confluence. This is the application name that you used to define Confluence in the Crowd 'Add Application' wizard above.
      • Application Password – Enter the password that you defined for Confluence in the Crowd 'Add Application' wizard above.
      • Crowd Permissions – Select Read/Write.
    • Leave the other settings at their default values and click the 'Test Settings' button to test the connection.
    • When you have a working connection, click 'Save'.
    • The 'User Directories' screen will appear. Now you will move the Crowd directory to the top of the list of directories. Click the blue upward arrow in the 'Order' column next to the 'Crowd Server', so that the Crowd directory moves to the top of the list.

      Here is a summary of how the directory order affects the processing:

      • The order of the directories is the order in which they will be searched for users and groups.
      • Changes to users and groups will be made only in the first directory where the application has permission to make changes.
  8. Log out of Confluence, but leave Confluence running.
  9. Log in to Confluence again, with the same username charlie and Charlie's password in Crowd.
    You are now authenticating via Crowd!
  10. Leave Crowd up and running, but shut down Confluence. (Press Ctrl+C in your Confluence server command window or run {CONFLUENCE_INSTALL}\bin\shutdown.bat (on Windows) or {CONFLUENCE_INSTALL}/bin/shutdown.sh (on UNIX).)
  11. Configure the Confluence property files for SSO:
    • Edit the {CONFLUENCE_INSTALL}/confluence/WEB-INF/classes/seraph-config.xml file.
    • Comment out the default authenticator node: 
      <!-- <authenticator class="com.atlassian.confluence.user.ConfluenceAuthenticator"/> -->
    • Uncomment the line that contains the new authenticator: 
      <authenticator class="com.atlassian.confluence.user.ConfluenceCrowdSSOAuthenticator"/>
    • Save the seraph-config.xml file.
    • Copy the crowd.properties file from {CROWD_INSTALL}/client/conf/ to {CONFLUENCE_INSTALL}/confluence/WEB-INF/classes, replacing the existing file.
    • Edit the {CONFLUENCE_INSTALL}/confluence/WEB-INF/classes/crowd.properties file and change the following properties:
      • application.name: confluence
      • application.password – Enter the password that Confluence will use to access Crowd. This must be the same password as you entered in the Crowd 'Add Application' wizard above.
    • Save the crowd.properties file.
  12. You now have SSO across Confluence, JIRA and Crowd! Try it:
    • Start your Confluence server again, and go to your Confluence URL in your browser, e.g. http://www.foobar.com:8090.
    • If you are already logged in to Crowd, you will not need to log in to Confluence. SSO ensures that you are already logged in as charlie.
    • Log out of Confluence.
    • Go to Crowd and click an option. Crowd will prompt you to log in. When you logged out of Confluence, SSO ensured that you logged out of Crowd and JIRA too.
    • Log in to JIRA, Confluence or Crowd. You will be logged in to all three.

Full details are in the Crowd documentation and the Confluence administrator's guide.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 5. Get JIRA and Confluence Talking

In this step you will set up the trusted communication channel between your JIRA and Confluence sites, so that you can display JIRA information on Confluence pages and Confluence information on the JIRA dashboard. This will be a two-way trust relationship: Confluence will trust JIRA and JIRA will trust Confluence. You will also make your Confluence gadgets available in JIRA.

  1. Make sure that both JIRA and Confluence are running.
  2. Go to your Confluence URL in your browser, e.g. http://www.foobar.com:8090.
  3. Select 'Application Links' from the 'Administration' section of the Confluence Administration Console.
  4. The 'Configure Application Links' screen will appear. Click 'Add Application Link'.
  5. The first screen of the 'Add Application Link' wizard will appear. Copy the base URL for your JIRA site (e.g. http://coopers:8080 or http://www.foobar.com:8080) and paste it into the 'Server URL' field.
  6. Click 'Next'.
  7. The 'Link to JIRA' screen will appear. Enter the following information:
    • Create a link back to this server – This option is selected by default. Let it remain selected.
    • Username: charlie. This is the username of the administrator on your JIRA site.
    • Password – Enter Charlie's password in JIRA.
    • Reciprocal Link URL – Leave this field at its default value, pointing to your Confluence site.
  8. Click 'Next'.
  9. The 'Set Users and Trust' screen will appear. Enter the following information:
    • The servers have the same set of users – This option is selected by default. Let it remain selected.
    • These servers fully trust each other – This option is selected by default. Let it remain selected.
  10. Click 'Create'.
  11. Now you will make your Confluence gadgets available in JIRA, so that JIRA users will be able to add any Confluence gadget to their dashboards. Go to your JIRA browser window and click 'Dashboards' in JIRA's top navigation bar.
  12. Click 'Add Gadget'.
  13. The 'Gadget Directory' popup window will appear. Click 'Gadget Subscriptions'.
  14. The 'Gadget Subscriptions' popup window will appear. Click 'Add Subscription'.
  15. The 'Add Subscriptions' popup window will appear. Copy the base URL for your Confluence site (e.g. http://coopers:8090 or http://www.foobar.com:8090) and paste it into the text box on the screen.
  16. Click 'Add Subscription'.
  17. Click 'Finished'.
    The Confluence gadgets are now available in your JIRA gadget directory. You have not yet added them to your JIRA dashboard. We will do that in a later step.

Screenshot 3 (click to enlarge): Adding JIRA as a trusted application in Confluence



The Confluence documentation has the details about application links and trusted applications.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 6. Create a Wiki Space

Now you can create a space in Confluence. A 'space' is a logical collection of pages, comparable to a library. A space is configurable and managed independently within the wiki site. It is almost like a wiki within a wiki.
The Atlassian Confluence demonstration space was created for you when you set up Confluence above.

  1. Click 'Dashboard' at the top left of the Confluence screen.
  2. Click 'Add Space' on the left-hand side of the screen.
  3. The 'Create Space' screen will appear. Configure your space settings:
    • Enter a space name: Dragons
    • Enter a space key: DRA
    • Who can use this space? – Leave the default settings as they are.
    • Choose Theme – Leave the default settings as they are (that is, 'Global Look and Feel').
    • Click 'OK'.
  4. The 'Home' page of your new 'Dragons' space will appear, with some default content. Now you can edit the home page as you like. For this exercise, you will add a Charlie badge:
    • Right-click on the image of the Charlie badge at the bottom of this documentation page and save it to your desktop. The file name is 'dragon_badge04.png'.
    • Click 'Edit' at the top right of your new Dragons home page in your own Confluence site.
    • The wiki rich text editor will open. If prompted, allow 'Gears' access to your site. This will allow you to drag and drop images and other attachments onto your wiki page.
    • Select and delete all the text in the editor pane. You will start with an empty page.
    • Make sure your cursor is at the top of the editor pane.
    • Click the 'Insert/Edit Image' icon in the editor toolbar.
    • The 'Insert Image' popup window will appear. Browse to your desktop and upload the Charlie badge image that you saved earlier. Alternatively, you can drag and drop the image from your desktop into the 'Insert Image' window.
    • The image will appear in the preview panel of the 'Insert Image' window. Click 'Insert'.
    • The image will appear in the editor pane of your home page.
    • Click 'Save' to save your updated wiki page.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 7. Add Some JIRA Issues to your Confluence Page

Now you can put some interesting JIRA content into your page. What's more, you can insert an issue into JIRA directly from your Confluence page and then display the issue on the page.

  1. Edit the Confluence page again.
  2. Place your cursor immediately after your Charlie badge image and press 'Enter' to start a new line.
  3. Enter the following text onto the page: My JIRA issues.
  4. Select the text that you have just entered and format it as a heading level 2. (Click the formatting dropdown menu on the left-hand edge of the editor tool bar. By default it formats your text as 'Paragraph'.)
  5. Deselect the text and then press 'Enter' to start a new line.
  6. Follow the steps below to add a JIRA macro to your page, showing a dynamic list of issues drawn from the 'Dragons' project on your JIRA site.
    • Click the 'Insert JIRA Issue' icon in the editor toolbar.
    • The 'Insert JIRA Issue' popup window will appear. Click 'Search' in the left-hand panel.
    • Enter the following JQL (JIRA Query Language) into the search box: project = DRA.
    • Click 'Search'.
    • A list of issues will appear, matching your search query. Select the option to 'Insert all query results as a table'.
    • Click 'Insert'.
    • The JIRA macro will appear on your page. In edit mode it looks like this: 
      {jira:project = DRA|server=Your Company JIRA}
  7. Click the 'Preview' tab to see a preview of the page. You will see a list of the JIRA issues in your 'Dragons' project.
  8. Click the 'Rich Text' tab to return to the editor.
  9. Enter the following text onto the page, and format it as a heading level 2: Reporting a new issue.
  10. Start a new line.
  11. Follow the steps below to add a new issue into JIRA and display the issue on your Confluence page:
    • Click the 'Insert JIRA Issue' icon in the editor toolbar.
    • The 'Insert JIRA Issue' popup window will appear. Click 'Create New Issue' in the left-hand panel.
    • Enter the following information:
      • Project: Dragons
      • Issue Type: Bug
      • Summary: The purple dragon melted my chocolate
      • Version/s: 2.0.S2
      • Description: The dragon tried to eat my chocolate and flamed it by mistake.
    • Click 'Insert'.
    • You now have a new issue DRA-4 in JIRA. In addition, a new JIRA macro will appear on your Confluence page, showing only the issue that you have created in JIRA. In edit mode the macro looks like this: 
      {jira:DRA-4|server=Your Company JIRA}
  12. Save the page.

Screenshot 4 (click to enlarge): Your updated Dragons home page in Confluence

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 8. Add a Confluence Gadget to JIRA

Now you will add the Confluence 'Activity Stream' gadget to your JIRA Dragon Development Dashboard.

  1. Click 'Dashboards' at top left of your JIRA screen.
  2. Your 'Dragon Development Dashboard' will appear. Click 'Add Gadget'.
  3. The 'Gadget Directory' will appear, showing a list of the available gadgets for your JIRA dashboard. Enter 'activity' into the search box at top right of the Gadget directory screen.
  4. The list of gadgets will change, to show only the gadgets that match your search term. You will see two 'Activity Stream' gadgets, once for JIRA and one for Confluence. To find the Confluence one, look at the gadget URL and find the URL that contains port '8090'.
  5. Click 'Add it Now' under the appropriate gadget. The gadget will be highlighted for a short time and the button's wording will change to 'Adding', while JIRA adds the gadget to the dashboard.
  6. Click 'Finished' to go back to your dashboard.
  7. Configure the 'Activity Stream' gadget:
    • Enter 'Confluence Dragons Activity' in the 'Title' field.
    • Select 'Dragons' in the 'Projects' field.
    • Click the dropdown arrow next to 'Refresh Interval' and select 'Every 15 Minutes'.
    • Leave the other fields at their default values and click 'Save'.
  8. Re-arrange your dashboard:
    • Drag the 'Projects' gadget to the right and drop it under the 'Assigned to Me' gadget.
    • Drag the 'Agile Gadget' to the bottom right.
  9. Choose a different colour for your 'Activity Stream' gadget:
    • Move your cursor pointer over the gadget and click the downward-pointing arrow at top right of the gadget frame.
    • Select the red square in the row of colours.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Victory!

Your JIRA dashboard now has 4 gadgets:

  • The Confluence 'Activity Stream' gadget
  • The 'Assigned to Me' gadget
  • The 'Projects' gadget
  • The GreenHopper 'Agile Gadget'

Screenshot 5 (click to enlarge): JIRA dashboard with 4 gadgets



Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.
Grab your Shield and Move to the Next Stage

Attachments:
PGAdminConfluenceDB.png (image/png)
PGAdminConfluenceDB.png (image/png)
ConfluenceDemoSpace.png (image/png)
InsertImageIcon.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceExternalGadgets.png (image/png)
JIRATrustedApp.png (image/png)
JIRATrustedApp.png (image/png)
ConfluenceDragonSpaceV2.png (image/png)
InsertMacroIcon.png (image/png)
ConfluenceDragonSpaceV2.png (image/png)
ConfluenceExternalGadgets.png (image/png)
JIRADashboardStage4.png (image/png)
ConfluenceExternalGadgets.png (image/png)
ConfluenceDragonSpaceV2.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceExternalGadgets.png (image/png)
JIRADashboardStage4.png (image/png)
JIRATrustedApp.png (image/png)
JIRADashboardStage4.png (image/png)
JIRATrustedApp.png (image/png)
PGAdminConfluenceDB.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceExternalGadgets.png (image/png)
ConfluenceDemoSpace-v5.png (image/png)
ConfluenceAppLinks.png (image/png)
ConfluenceExternalGadgets-v5.png (image/png)
ConfluenceHomePage.png (image/png)
JIRADashboardStage4-v5.png (image/png)
InsertJIRAIcon.png (image/png)
Document generated by Confluence on May 22, 2011 21:55